@sindresorhus/slugify

What is @sindresorhus/slugify?

@sindresorhus/slugify is a simple and efficient npm package used to convert strings into URL-friendly slugs. It handles various edge cases, such as special characters, spaces, and diacritics, making it a reliable choice for generating slugs from user input or other text data.

What are @sindresorhus/slugify's main functionalities?

Basic Slugification

This feature converts a basic string into a URL-friendly slug by replacing spaces with hyphens and converting the text to lowercase.

const slugify = require('@sindresorhus/slugify');
const slug = slugify('Hello World!');
console.log(slug); // 'hello-world'

Custom Replacement Characters

This feature allows you to customize the separator character used in the slug, such as using an underscore instead of a hyphen.

const slugify = require('@sindresorhus/slugify');
const slug = slugify('Hello World!', { separator: '_' });
console.log(slug); // 'hello_world'

Handling Diacritics

This feature removes diacritics from characters, ensuring that the resulting slug is composed of standard ASCII characters.

const slugify = require('@sindresorhus/slugify');
const slug = slugify('Crème brûlée');
console.log(slug); // 'creme-brulee'

Custom Replacement Map

This feature allows you to define custom replacements for specific characters or strings, providing greater control over the slugification process.

const slugify = require('@sindresorhus/slugify');
const slug = slugify('foo@bar', { customReplacements: [['@', 'at']] });
console.log(slug); // 'foo-at-bar'

Other packages similar to @sindresorhus/slugify

slug

The 'slug' package is another popular choice for generating URL-friendly slugs. It offers similar functionality to @sindresorhus/slugify, including handling special characters and diacritics. However, it provides more configuration options and supports transliteration for non-Latin characters.

speakingurl

The 'speakingurl' package is designed to create human-readable slugs from strings. It supports a wide range of languages and character sets, making it a versatile choice for internationalization. Compared to @sindresorhus/slugify, it offers more extensive language support and customization options.

limax

The 'limax' package is a slug generator that focuses on transliteration and supports multiple languages. It is similar to @sindresorhus/slugify in terms of basic functionality but provides additional features for handling non-Latin scripts and complex transliterations.

README

slugify

Slugify a string

Useful for URLs, filenames, and IDs.

It handles most major languages, including German (umlauts), Vietnamese, Arabic, Russian, and more.

Install

$ npm install @sindresorhus/slugify

Usage

import slugify from '@sindresorhus/slugify';

slugify('I ♥ Dogs');
//=> 'i-love-dogs'

slugify('  Déjà Vu!  ');
//=> 'deja-vu'

slugify('fooBar 123 $#%');
//=> 'foo-bar-123'

slugify('я люблю единорогов');
//=> 'ya-lyublyu-edinorogov'

API

slugify(string, options?)

string

Type: string

String to slugify.

options

Type: object

separator

Type: string
Default: '-'

import slugify from '@sindresorhus/slugify';

slugify('BAR and baz');
//=> 'bar-and-baz'

slugify('BAR and baz', {separator: '_'});
//=> 'bar_and_baz'

slugify('BAR and baz', {separator: ''});
//=> 'barandbaz'

lowercase

Type: boolean
Default: true

Make the slug lowercase.

import slugify from '@sindresorhus/slugify';

slugify('Déjà Vu!');
//=> 'deja-vu'

slugify('Déjà Vu!', {lowercase: false});
//=> 'Deja-Vu'

decamelize

Type: boolean
Default: true

Convert camelcase to separate words. Internally it does fooBar → foo bar.

import slugify from '@sindresorhus/slugify';

slugify('fooBar');
//=> 'foo-bar'

slugify('fooBar', {decamelize: false});
//=> 'foobar'

customReplacements

Type: Array<string[]>
Default: [ ['&', ' and '], ['🦄', ' unicorn '], ['♥', ' love '] ]

Add your own custom replacements.

The replacements are run on the original string before any other transformations.

This only overrides a default replacement if you set an item with the same key, like &.

import slugify from '@sindresorhus/slugify';

slugify('Foo@unicorn', {
	customReplacements: [
		['@', 'at']
	]
});
//=> 'fooatunicorn'

Add a leading and trailing space to the replacement to have it separated by dashes:

import slugify from '@sindresorhus/slugify';

slugify('foo@unicorn', {
	customReplacements: [
		['@', ' at ']
	]
});
//=> 'foo-at-unicorn'

Another example:

import slugify from '@sindresorhus/slugify';

slugify('I love 🐶', {
	customReplacements: [
		['🐶', 'dogs']
	]
});
//=> 'i-love-dogs'

preserveLeadingUnderscore

Type: boolean
Default: false

If your string starts with an underscore, it will be preserved in the slugified string.

Sometimes leading underscores are intentional, for example, filenames representing hidden paths on a website.

import slugify from '@sindresorhus/slugify';

slugify('_foo_bar');
//=> 'foo-bar'

slugify('_foo_bar', {preserveLeadingUnderscore: true});
//=> '_foo-bar'

preserveTrailingDash

Type: boolean
Default: false

If your string ends with a dash, it will be preserved in the slugified string.

For example, using slugify on an input field would allow for validation while not preventing the user from writing a slug.

import slugify from '@sindresorhus/slugify';

slugify('foo-bar-');
//=> 'foo-bar'

slugify('foo-bar-', {preserveTrailingDash: true});
//=> 'foo-bar-'

preserveCharacters

Type: string[]
Default: []

Preserve certain characters.

It cannot contain the separator.

For example, if you want to slugify URLs, but preserve the HTML fragment # character.

import slugify from '@sindresorhus/slugify';

slugify('foo_bar#baz', {preserveCharacters: ['#']});
//=> 'foo-bar#baz'

slugifyWithCounter()

Returns a new instance of slugify(string, options?) with a counter to handle multiple occurrences of the same string.

Example

import {slugifyWithCounter} from '@sindresorhus/slugify';

const slugify = slugifyWithCounter();

slugify('foo bar');
//=> 'foo-bar'

slugify('foo bar');
//=> 'foo-bar-2'

slugify.reset();

slugify('foo bar');
//=> 'foo-bar'

Use-case example of counter

If, for example, you have a document with multiple sections where each subsection has an example.

## Section 1

### Example

## Section 2

### Example

You can then use slugifyWithCounter() to generate unique HTML id's to ensure anchors will link to the right headline.

slugify.reset()

Reset the counter

Example

import {slugifyWithCounter} from '@sindresorhus/slugify';

const slugify = slugifyWithCounter();

slugify('foo bar');
//=> 'foo-bar'

slugify('foo bar');
//=> 'foo-bar-2'

slugify.reset();

slugify('foo bar');
//=> 'foo-bar'

Related

• slugify-cli - CLI for this module
• transliterate - Convert Unicode characters to Latin characters using transliteration
• filenamify - Convert a string to a valid safe filename